package com.videri.match.client;

import com.google.gwt.user.client.rpc.AsyncCallback;

public interface VideriChatServiceAsync{
	
	/**
	 * This is what will get called when a user types a message and hits 'enter' in the chat room.
	 * @param user This is the cookie, not the handle, of the user who's submitting the message
	 * @param message This is the text of the message the user wants to send.
	 * @param recipients This is a list of the handles of the users this message will go to.  
	 * If it is an empty array (recipients.length == 0), the message is public and will go to everyone in the room.
	 * @return Either an empty string or an error message.  The message may not be accepted if:
	 * 1) The cookie is invalid
	 * 2) The message was too long
	 * 3) The user has been sending too many messages (spambot!)
	 * 
	 * Invalid recipient usernames should not cause an error message (just nothing will happen)
	 */
	public void addMessage(String user, String message, String[] recipients, AsyncCallback callback);
	/**
	 * This is what users will poll every so often to get any messages that have been sent to them since they last called the method.
	 * The user's message queue should be flushed each time this method is called.
	 * Note that this means the message queues have to be synchronized, since multiple threads may access the data structure at once.
	 * The list of messages is returned as a ChatMessageList object.
	 * @param user The cookie of the user who is requesting his or her messages.
	 * @return a ChatMessageList representing the new messages (since last time this method was called for this user)
	 */
	public void getMessages(String user, AsyncCallback callback);
	/**
	 * Returns a list of the handles of all the users in the specified chat room
	 * @param user The cookie of the user who is requesting the info.  If they aren't in the chat room, they can't see the info, and an empty array will be returned.
	 * @param room The room being queried.
	 * @return A list of handles if 'user' is in 'room', otherwise empty array. 
	 */
	public void getUserList(String user, String room, AsyncCallback callback);
	/**
	 * This method is used for a user to request to join a chat room.
	 * @param room The room the user wants to join
	 * @param user The cookie of the user who wants to join
	 * @return true if user is allowed to join the room and has been added, false otherwise.
	 */
	public void joinRoom(String user, String room, AsyncCallback callback);
	
	/**
	 * This is how the user finds out which room they're logged into.
	 * @param user The cookie of the user who wants to find out what room they're in
	 * @return Either the String identifier of the room they're in, or null if they're not in a room or if the cookie is invalid.
	 */
	public void getRoom(String user, AsyncCallback callback);
	/**
	 * Removes the user specified by the cookie from whichever room they happen to be in.
	 * @param user The cookie of the user who wants to leave.  They can only be in one room at a time, so they don't have to specify which room they want to leave.
	 */
	public void leaveRoom(String user, AsyncCallback callback);
}
